QuickTime 3 Reference
| Previous | Chapter contents | Chapter top | Section top | Next |
Once you have a list of effects, you are ready to ask QuickTime to display a dialog box that allows the user to choose and customize an effect. This is known as the standard parameters dialog box . You use the QTCreateStandardParameterDialog function to display the dialog box.
Your application can use this function either to display a stand-alone dialog box, or to add the user interface elements from the standard parameter dialog box to one of the application's own dialog boxes. These options are discussed separately in the following sections.
For full details of the QTCreateStandardParameterDialog function, see the reference section "QTCreateStandardParameterDialog" .
When you call QTCreateStandardParameterDialog , QuickTime creates a standard parameters dialog box. The contents of the dialog box will vary, depending on the list of effects you passed to the function and the set of parameters that the currently chosen effect has.
Calling QTCreateStandardParameterDialog does not display the standard parameters dialog box, it only prepares it for display. The dialog box is shown the first time you call QTIsStandardParameterDialogEvent to process events for the dialog box. Event handling is described in "Processing Standard Parameter Dialog Box Events" .
The standard parameters dialog box for Apple's Film Noise effect is shown in Figure 20-3 .
Figure 3 The standard parameters dialog box showing Apple's Film Noise effect
Notice that the dialog box has three main sections. In the upper left corner is a scrolling list of all the components. To the right of this are displayed the parameters of the chosen effect. As you select different items in the list of effects, the parameters change appropriately. Finally, there is the effect preview, which is below the list of effects. This shows a preview of the currently chosen effect and parameter settings applied to a short preview movie clip.
The function call to create and display this dialog box is:
QTCreateStandardParameterDialog(theEffectList,
theEffectParameters,
0,
&createdDialogID);
The variable theEffectList holds list of effects that was returned by QTGetEffectsList . You can also pass NIL for this value, in which case QTCreateStandardParameterDialog calls QTGetEffectsList to generate the list of all the currently installed effects, then shows these effects. The argument theEffectParameters contains a QTAtomContainer which holds the initial values of the effect's parameters. In most cases, you should pass an empty QTAtomContainer as this argument, in which case the default values of each effect are shown. When the user selects the dialog box's OK button, the chosen effect's parameter values are written into theEffectParameters .
The third argument contains dialog options. See the reference section "QTCreateStandardParameterDialog" for details of the possible options values that can be passed.
The createdDialog argument returns an ID number that is passed to the other functions that deal with the standard parameters dialog box. This is explained in detail in the next section.
Once the dialog box has been created, you must process events sent to it using an event loop. You repeatedly call WaitNextEvent and pass the events returned through the QTIsStandardParameterDialogEvent function.
The QTIsStandardParameterDialogEvent function checks each event to see if it relates to the standard parameters dialog box. You should continue to handle events that are not related to the standard parameters dialog box as normal.
You should not use the ModalDialog function to process events for a standard parameters dialog box. The ModalDialog function is not guaranteed to work correctly in all circumstances with a standard parameters dialog box.
You pass the event record returned from WaitNextEvent to the function QTIsStandardParameterDialogEvent , then check the return value to find out how the events was handled. The possible return values are:
The QTIsStandardParameterDialogEvent function may also return error codes, as described in "QuickTime Video Effects Reference" in this chapter. Your application should only process the event returned from WaitNextEvent if QTIsStandardParameterDialogEvent returns featureUnsupported .
The code in Listing 20-5 is an example event loop showing how QTIsStandardParameterDialogEvent is used.
Listing 5 An example event loop showing use of QTIsStandardParameterDialogEvent
while (result == noErr)
{
EventRecord theEvent;
WaitNextEvent(everyEvent, &theEvent, 0, nil);
result = QTIsStandardParameterDialogEvent(&theEvent, createdDialogID);
switch (result)
{
case featureUnsupported:
{
result = noErr;
switch (theEvent.what)
{
case updateEvt:
BeginUpdate((WindowPtr) theEvent.message);
EndUpdate((WindowPtr) theEvent.message);
break;
}
break;
}
case codecParameterDialogConfirm:
case userCanceledErr:
QTDismissStandardParameterDialog(createdDialogID);
createdDialogID = nil;
break;
}
}
}
| Previous | Chapter contents | Chapter top | Section top | Next |